            Description: PCI Express UART Linux 2.6 driver patch
          ========================================================

The expresso_linux2.6_uart serial device driver patch supports the Oxford
Semiconductor Expresso family of PCI Express to Serial bridge devices. This
includes the:
        
        OXPCIe952
        OXPCIe954
        OXPCIe958
        OXPCIe200
    
This patch has been developed on the 2.6.17.7 Linux Kernel

This README includes instructions for applying the patch, along with some useful
prerequisites and considerations for the user.

Prerequisites:-
===============
Before getting started with the Linux 2.6 serial device driver patch for the 
Oxford Semiconductor Expresso PCIe family of devices there are a few 
prerequisites for users to consider on their Linux 2.6 system.

Please note that the following README for the serial patch makes the assumption 
that the user is working on a PC distribution of Linux such as Red Hat, Suse or 
Fedora etc... The patch will be the same or similar for any Linux 2.6 based 
system, however the following steps may change depending on the users system.

The serial device driver patch will be applied to the source code for the Linux 
OS. Hence the user will need the source code for their particular version of the
Linux kernel. There are two general options for acquiring the Linux kernel 
source code, the user can either download the source for their particular 
distributions kernel or the user can download the Linux communities "vanilla" 
kernel from www.kernel.org. To rebuild the patched serial driver the user will 
also need the kernel build tools relative to their Linux distribution. For more 
information on the source code and the build tools for the users system one 
should consult the documentation for their particular distribution.

In general, the kernel source code is copied to /usr/src/. As some distributions
may do this slightly differently, we will make the assumption in this document
that the root directory of the kernel source code is located at 
/usr/src/linux-2.6

General Tips:-
==============
In general the Linux kernel pre-built with each Linux distribution will have the
serial driver built into the kernel, and not built as a kernel loadable module.
This means that regardless of whether the user would like to have the serial 
driver for the Oxford UART device built into the kernel, or available as a 
kernel loadable module the user will have to rebuild the full kernel.

To rebuild the kernel with the serial driver as a kernel loadable module, the 
user should use a tool such as menuconfig to configure the kernels .config file.

 - From the command line navigate to the root directory of the linux 
   kernel source:
        ~> cd /usr/src/linux-2.6
 - Start "menuconfig" to configure the .config file:
        ~> make menuconfig
 - Within the "menuconfig" utility:
        - The first page is the "Linux Kernel Configuration" page. On this 
          page select the Device Drivers menu.
        - From the "Device Drivers" menu one should select the "Character 
          Devices" menu.
        - From the "Character Devices" menu, select "Serial Drivers".
        - To build the serial drivers as part of the kernel confirm that 
          the entry for "8250/16550 and compatible serial support" is 
          selected as {*}.
        - To build the serial drivers as a kernel loadable module confirm 
          that the entry for "8250/16550 and compatible serial support" 
          is selected as {M}.
        - Once all changes have been made, exit back through the menus 
          and select "Yes" to save the new .config file. Now proceed to 
          build your kernel and modules.

Also, in general the Linux kernel pre-built with each Linux distribution will be
set to only enumerate 4 serial ports at runtime. As many of the Oxford devices 
contain 4 and 8 UARTs this can prove to be a problem. As the user will need to 
rebuild the kernel already, this is easily resolved. 

 - From the command line navigate to the root directory of the linux 
   kernel source:
        ~> cd /usr/src/linux-2.6
 - Start "menuconfig" to configure the .config file:
        ~> make menuconfig
 - Within the "menuconfig" utility:
        - The first page is the "Linux Kernel Configuration" page. On this 
          page select the Device Drivers menu.
        - From the "Device Drivers" menu one should select the "Character 
          Devices" menu.
        - From the "Character Devices" menu, select "Serial Drivers".
        - To adjust the number of serial ports enumerated at runtime, 
          select "Number of 8250/16550 serial ports to register at runtime" 
          and enter a suitable number (e.g. 20).
        - Once all changes have been made, exit back through the menus 
          and select "Yes" to save the new .config file. Now proceed to 
          build your kernel and modules.

Building the Linux kernel from source code:-
============================================
Depending of the Linux distribution that the user has, and the build tools 
provided, building the kernel can be done in different ways. For most systems,
including Red Hat, Suse and Fedora, the following steps are used to build the 
Linux kernel from source code.

 - Navigate to the root directory of the Linux kernel source code:
        ~> cd /usr/src/linux-2.6
 - Build the kernel image:
        ~> make bzImage
 - Build the modules specified in the .config file:
        ~> make modules
 - Run the install scripts for the kernel loadable modules:
        ~> make modules_install
 - Run the install scripts for the kernel
        ~> make install

For more information on building the Linux kernel from source code, the user 
should refer to the documentation for their chosen distribution.

Note that the steps above will not work for a debian based system such as 
Ubuntu, and the user should look to their distribution's documentation for 
guidance.

How to apply the serial device driver patch:-
=============================================
If the user plans on building the serial driver as part of the Linux kernel 
(i.e. not as a kernel loadable module) then you will have to apply the patch to
the serial driver code within the Linux source code directory.

If the user would like to build the serial driver as a kernel loadable module 
then the user can take a copy of the serial device driver source code from 
within the Linux kernel source code, copy this driver source to a working 
directory such as one's home directory, and then patch this copy of the driver. 
The advantage of working on a copy is that the user will still have a clean copy
of the kernel source just in case.

The Linux serial device driver is located at:
~> /usr/src/linux-2.6/drivers/serial

To apply the patch:
 - Paste the expresso_linux2.6_uart patch file into the serial folder.
 - Open a terminal and navigate to the serial folder.
 - To apply the patch, enter the following command:
    ~> patch -p0 < expresso_linux2.6_uart

The patch will add code to the file "8250_pci.c". It is a simple patch that 
basically adds baud_base and base address information for the Expresso devices
and adds a small routine to check the number of UART ports available on the 
device. Because the "8250_pci.c" can be updated at any time by the community,
the patch may fail. If this happens the user is encouraged to take a look at 
the contents of the patch and try adding this manually.

To build the patched serial device driver into the kernel the user will now
simply have to follow the usual build steps as described above.

To build the patched serial driver as a kernel loadable module:-
================================================================
Kernel loadable modules can be dynamically loaded and unloaded from the running
Linux kernel. This can be very advantageous depending on the user needs. 
To build the patched serial driver as a kernel loadable module, the user must
have first satisfied the above prerequisite of configuring the kernel's .config
file to build the serial driver as a kernel loadable module. To then build the
module:

 - Navigate to the serial device driver directory. I.e. if a copy of the serial
   device driver has been copied to /home/user/ and then patched as above:
        ~> cd /home/user/serial/
 - To build the patched serial device driver enter the following command:
        ~> make -C /usr/src/linux-2.6 M=$PWD modules

This will generate the serial driver kernel loadable modules (.ko files) in 
/home/user/serial. The serial driver for the Expresso devices will be "8250.ko",
and the module "8250_pci.ko" performs the binding of the driver to the Oxford
Expresso device.

To load the kernel loadable modules:
 - Insert the serial device driver module (from /home/usr/serial):
        ~> insmod 8250.ko
 - Insert the serial PCI module:
        ~> insmod 8250_pci.ko

Note that often the serial device driver module will already be loaded at 
startup, in which case the vanilla 8250.ko and 8250_pci.ko modules will need 
to be removed (see below) before the above insmod commands will work.

To see the debug output from the Linux kernel, the user can open another 
terminal and enter:
        ~> tail -f /var/log/messages
        
To see a list of the kernel loadable modules currently loaded on the system:
        ~> lsmod
        
To unload the modules:
        ~> rmmod 8250_pci.ko
        ~> rmmod 8250.ko



